<!-- 
  ****************************************************************************
  * Copyright 2018-2019,2020 Thomas E. Dickey                                *
  * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: panel.3x,v 1.28 2020/02/02 23:34:34 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>panel 3x</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY>
<H1 class="no-header">panel 3x</H1>
<PRE>
<STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>                                                            <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       panel - panel stack extension for curses


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;panel.h&gt;</STRONG>

       <STRONG>cc</STRONG> <STRONG>[flags]</STRONG> <STRONG>sourcefiles</STRONG> <STRONG>-lpanel</STRONG> <STRONG>-lncurses</STRONG>

       <STRONG>PANEL</STRONG> <STRONG>*new_panel(WINDOW</STRONG> <STRONG>*win);</STRONG>
       <STRONG>int</STRONG> <STRONG>bottom_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>int</STRONG> <STRONG>top_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>int</STRONG> <STRONG>show_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>void</STRONG> <STRONG>update_panels(void);</STRONG>
       <STRONG>int</STRONG> <STRONG>hide_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>WINDOW</STRONG> <STRONG>*panel_window(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>int</STRONG> <STRONG>replace_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*window);</STRONG>
       <STRONG>int</STRONG> <STRONG>move_panel(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>int</STRONG> <STRONG>starty,</STRONG> <STRONG>int</STRONG> <STRONG>startx);</STRONG>
       <STRONG>int</STRONG> <STRONG>panel_hidden(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>PANEL</STRONG> <STRONG>*panel_above(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>PANEL</STRONG> <STRONG>*panel_below(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>int</STRONG> <STRONG>set_panel_userptr(PANEL</STRONG> <STRONG>*pan,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*ptr);</STRONG>
       <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*panel_userptr(const</STRONG> <STRONG>PANEL</STRONG> <STRONG>*pan);</STRONG>
       <STRONG>int</STRONG> <STRONG>del_panel(PANEL</STRONG> <STRONG>*pan);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       Panels  are  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> windows with the added feature of depth.  Panel
       functions allow the use of stacked windows and ensure the  proper  por-
       tions  of  each  window and the curses <STRONG>stdscr</STRONG> window are hidden or dis-
       played when panels are added, moved, modified or removed.  The  set  of
       currently  visible panels is the stack of panels.  The <STRONG>stdscr</STRONG> window is
       beneath all panels, and is not considered part of the stack.

       A window is associated with every panel.  The panel routines enable you
       to  create, move, hide, and show panels, as well as position a panel at
       any desired location in the stack.

       Panel routines are a functional layer added to  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  make  only
       high-level curses calls, and work anywhere terminfo curses does.


</PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
       <STRONG>new_panel(win)</STRONG>
              allocates   a   <STRONG>PANEL</STRONG>  structure, associates it with <STRONG>win</STRONG>, places
              the panel on the top of the stack  (causes  it to  be  displayed
              above any other panel) and returns a pointer to the new panel.

       <STRONG>update_panels</STRONG>
              refreshes  the  <EM>virtual</EM>  <EM>screen</EM> to reflect the relations between
              the panels in the stack, but does not call <STRONG>doupdate</STRONG>  to  refresh
              the  <EM>physical</EM>  <EM>screen</EM>.   Use  this  function and not <STRONG>wrefresh</STRONG> or
              <STRONG>wnoutrefresh</STRONG>.  <STRONG>update_panels</STRONG> may be called more than once before
              a call to <STRONG>doupdate</STRONG>, but <STRONG>doupdate</STRONG> is the function responsible for
              updating the <EM>physical</EM> <EM>screen</EM>.

       <STRONG>del_panel(pan)</STRONG>
              removes the given panel from  the   stack  and  deallocates  the
              <STRONG>PANEL</STRONG> structure (but not its associated window).

       <STRONG>hide_panel(pan)</STRONG>
              removes  the  given panel from the panel stack and thus hides it
              from view.  The <STRONG>PANEL</STRONG> structure is not lost, merely removed from
              the stack.

       <STRONG>panel_hidden(pan)</STRONG>
              returns  <STRONG>TRUE</STRONG> if the panel is in the panel stack, <STRONG>FALSE</STRONG> if it is
              not.  If the panel is a null pointer, return <STRONG>ERR</STRONG>.

       <STRONG>show_panel(pan)</STRONG>
              makes a hidden panel visible by placing it on top of the  panels
              in the panel stack.  See COMPATIBILITY below.

       <STRONG>top_panel(pan)</STRONG>
              puts  the given visible panel on top of all panels in the stack.
              See COMPATIBILITY below.

       <STRONG>bottom_panel(pan)</STRONG>
              puts panel at the bottom of all panels.

       <STRONG>move_panel(pan,starty,startx)</STRONG>
              moves the given panel window so that its upper-left corner is at
              <STRONG>starty</STRONG>, <STRONG>startx</STRONG>.  It does not change the position of the panel in
              the stack.  Be sure to use this function, not <STRONG>mvwin</STRONG>, to  move  a
              panel window.

       <STRONG>replace_panel(pan,window)</STRONG>
              replaces  the  current  window of panel with <STRONG>window</STRONG> (useful, for
              example if you want to resize a panel; if you're using  <STRONG>ncurses</STRONG>,
              you  can  call  <STRONG>replace_panel</STRONG> on the output of <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>).  It
              does not change the position of the panel in the stack.

       <STRONG>panel_above(pan)</STRONG>
              returns a pointer to the panel above pan.  If the panel argument
              is  <STRONG>(PANEL</STRONG>  <STRONG>*)0</STRONG>, it returns a pointer to the bottom panel in the
              stack.

       <STRONG>panel_below(pan)</STRONG>
              returns a pointer to the panel just below  pan.   If  the  panel
              argument is <STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>, it returns a pointer to the top panel in
              the stack.

       <STRONG>set_panel_userptr(pan,ptr)</STRONG>
              sets the panel's user pointer.

       <STRONG>panel_userptr(pan)</STRONG>
              returns the user pointer for a given panel.

       <STRONG>panel_window(pan)</STRONG>
              returns a pointer to the window of the given panel.


</PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
       Each routine that returns a pointer returns <STRONG>NULL</STRONG> if  an  error  occurs.
       Each  routine  that returns an int value returns <STRONG>OK</STRONG> if it executes suc-
       cessfully and <STRONG>ERR</STRONG> if not.


</PRE><H2><a name="h2-COMPATIBILITY">COMPATIBILITY</a></H2><PRE>
       Reasonable care has been taken  to   ensure   compatibility  with   the
       native   panel  facility introduced in System V (inspection of the SVr4
       manual pages suggests the programming  interface  is  unchanged).   The
       <STRONG>PANEL</STRONG>  data  structures  are  merely  similar.  The  programmer is cau-
       tioned not to directly use <STRONG>PANEL</STRONG> fields.

       The functions <STRONG>show_panel</STRONG> and <STRONG>top_panel</STRONG> are identical in this  implemen-
       tation,  and work equally well with displayed or hidden panels.  In the
       native System V implementation, <STRONG>show_panel</STRONG> is  intended  for  making  a
       hidden  panel  visible  (at  the  top  of  the  stack) and <STRONG>top_panel</STRONG> is
       intended for making an already-visible panel move to  the  top  of  the
       stack.  You are cautioned to use the correct function to ensure compat-
       ibility with native panel libraries.


</PRE><H2><a name="h2-NOTE">NOTE</a></H2><PRE>
       In your library list, libpanel.a should be  before  libncurses.a;  that
       is, you should say "-lpanel -lncurses", not the other way around (which
       would give a link-error with static libraries).


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       The panel facility was documented in SVr4.2 in <EM>Character</EM> <EM>User</EM> <EM>Interface</EM>
       <EM>Programming</EM> <EM>(UNIX</EM> <EM>SVR4.2)</EM>.

       It is not part of X/Open Curses.

       Aside  from  ncurses,  only  systems  based  on SVr4 source code, e.g.,
       Solaris provide this library.


</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
       panel.h interface for the panels library

       libpanel.a the panels library itself


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,

       This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200212).


</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
       Originally written by Warren Tucker &lt;wht@n4hgf.mt-park.ga.us&gt;,  primar-
       ily  to  assist  in  porting u386mon to systems without a native panels
       library.  Repackaged for ncurses by Zeyd ben-Halim.



                                                                     <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#h2-FUNCTIONS">FUNCTIONS</a></li>
<li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
<li><a href="#h2-COMPATIBILITY">COMPATIBILITY</a></li>
<li><a href="#h2-NOTE">NOTE</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-FILES">FILES</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
<li><a href="#h2-AUTHOR">AUTHOR</a></li>
</ul>
</div>
</BODY>
</HTML>
